import { Meta } from '@storybook/blocks';
import cssCustomPropertiesStorybookImage from './images/css-custom-properties-storybook.png'
import cssCustomPropertiesComponentImage from './images/css-custom-properties-component.png'

<Meta title="Documentation/Customizing Components Style" />

# How to customize a component's style?
> You can look at our [discussion](https://github.com/Trendyol/baklava/discussions/164) to know more about our decision process.

A design system is a set of design tokens and principles that aims to create consistency in terms of both experience and development. Also, it represents branding in terms of design. Every component is written with the design language that Baklava provides. It has intentionally limited flexibility. To prevent the loss of standards and experience, we don't want and let users change directly component's style. However, we allow users to create their theme and use it for Baklava.

In Baklava, we create __web components__. Our components work in a Shadow DOM. Therefore, components are isolated from the page DOM and their styles are scoped to their DOM. Thanks to this, style rules don't leak out and we can decide whether this rule can change or not by the user while developing the component. To create flexibility in components, we use CSS custom properties. If we need to allow users to customize styling options, we define them as CSS custom variables.


### For Contributors

All __private__ CSS variables should be defined under a wrapping element (For example: [.badge](https://github.com/Trendyol/baklava/blob/4ea8f5aca610a97c73898c8d13173da079a2c776/src/components/badge/bl-badge.css#L6)
for the badge component) __inside__ the component.
By doing this, we apply a __safer__ approach. We prevented developers to style components __unintentionally__. Thanks to this, we don't need to specify variables
with prefixes in every component. Therefore, should be no prefixes in local variables. Because those are only used inside a component.
However, if we want to add some flexibility, customizability, we define variables with components prefix like `--bl-badge-bg-color`.

#### Example

Let's take a badge component as an example:
```css
/* bl-badge.css */
:host {
  display: inline-block;
  max-width: 100%;
}

.badge {
    /* Variable definition start */
  --bg-color: var(--bl-badge-bg-color, var(--bl-color-primary-contrast));
  --color: var(--bl-badge-color, var(--bl-color-primary));
  --font: var(--bl-font-title-4-medium);
  --padding-vertical: var(--bl-size-3xs);
  --padding-horizontal: var(--bl-size-3xs);
  --margin-icon: var(--bl-size-3xs);
  --icon-size: var(--bl-size-s);
  --height: var(--bl-size-xl);
    /* Variable definition stop */

  /* ... */
  /* Using variables start */
  gap: var(--margin-icon);
  border-radius: var(--bl-size-4xs);
  padding: var(--padding-vertical) var(--padding-horizontal);
  background-color: var(--bg-color);
  color: var(--color, white);
  font: var(--font);
  height: var(--height);
  /* ... */
  /* Using variables end */
}
```
By the __nature__ of this component, we let users to change background color and color. To accomplish this,
we define a default variables `--bl-badge-bg-color` and `--bl-badge-color` and fill it with our default definitions like this:

```css
--bg-color: var(--bl-badge-bg-color, var(--bl-color-primary-contrast));
--color: var(--bl-badge-color, var(--bl-color-primary));
```

Therefore, if users want to change its background color and/or color, they should change `--bl-badge-bg-color` and/or `--bl-badge-color`.
```css
.wrapper {
  --bl-badge-bg-color: red;
  --bl-badge-color: white;
}
```
```js
<div class="wrapper">
  <bl-badge>badge component</bl-badge>
</div>
```


We __must__ define public variables in the component like this:

<img src={cssCustomPropertiesComponentImage} />

It will be shown in the storybook like this:

<img src={cssCustomPropertiesStorybookImage} />
